docs(architecture): concurrent config-write safety (#5) - #27
Merged
Conversation
Adds a "Concurrent config-write safety" subsection to ARCHITECTURE.md → Limits: links anthropics/claude-code#29217, the probe finding (didn't repro on v2.1.153), mitigations (max_parallel_workers 2-3, no concurrent sessions, keep updated), and the residual settings.json-staging risk mitigated by the explicit-staging rule. Docs-module slice of #5; the implementer staging rule already landed in #21. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011HosUeuSvhetARboEfDW6K
Reviewer nit (both lenses, non-blocking): "keep max_parallel_workers at 2-3 (already advised)" was imprecise vs the repo's other figures. Reword to point at the 2-4 ceiling stated earlier in the same section and note the self-adapter ships 2. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011HosUeuSvhetARboEfDW6K
robercano
approved these changes
Jul 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a "Concurrent config-write safety" subsection to
docs/ARCHITECTURE.md→ Limits to respect.Covers the anthropics/claude-code#29217 concern (non-atomic concurrent writes to
~/.claude.json), which matters because this template fans out to parallel worktree workers:max_parallel_workerslow (the 2–4 ceiling already advised; self-adapter ships 2), no concurrent sessions from the same home dir, keep Claude Code updated..claude/settings.json— mitigated by the pre-approved allow-list + the implementer rule to stage explicit paths only (nevergit add -A).Framed explicitly as an upstream concern the template documents/mitigates, not fixes.
Scope
Docs-module slice of #5 (adapter
.claude/self/gates.json, moduledocs). The implementer staging rule referenced here already landed in #21. Single file:docs/ARCHITECTURE.md.Gates
GATES_FILE=.claude/self/gates.jsonbuild + lint + test all green.Review
Reviewer lenses per self-adapter (correctness, tests), consensus=all: both approved (high confidence). Second commit addresses both lenses' shared non-blocking nit (aligned the
max_parallel_workersphrasing).Closes #5.
🤖 Generated with Claude Code